Add a Plugin

eleventyNavigation: key: Render order: 0 excerpt: A plugin to add shortcodes to render an Eleventy template string (or file) inside of another template. communityLinksKey: syntaxrender

Render {% addedin "1.0.0" %}

{% tableofcontents %}

{{ eleventyNavigation.excerpt }}

Template Compatibility

This plugin adds a renderTemplate and renderFile asynchronous shortcode to:

Everything you’ve added to project’s configuration file will also be available in these renders too: shortcodes, filters, etc. That means you can nest 😱 them, too!

Installation

This plugin is bundled with Eleventy core so it doesn’t require additional installation. But you do have to add it to your configuration file (probably .eleventy.js) with addPlugin:

{% codetitle ".eleventy.js" %}

const { EleventyRenderPlugin } = require("@11ty/eleventy");

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(EleventyRenderPlugin);
};
Expand to view all of the Plugin Options

{% codetitle ".eleventy.js" %}

const { EleventyRenderPlugin } = require("@11ty/eleventy");

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(EleventyRenderPlugin, {
    tagName: "renderTemplate",  // Change the renderTemplate shortcode name
    tagNameFile: "renderFile",  // Change the renderFile shortcode name
  });
};

{% callout "info", "md" %}You’re only allowed one module.exports in your configuration file, so make sure you only copy the require and the addPlugin lines above!{% endcallout %}

Usage

renderTemplate

Use the renderTemplate paired shortcode to render a template string.

{% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "rendertmpl"} %}

{% codetitle "Liquid", "Syntax" %}

{% raw %}

{% renderTemplate "md" %}
# I am a title

* I am a list
* I am a list
{% endrenderTemplate %}

{% endraw %}

{% codetitle "Nunjucks", "Syntax" %}

{% raw %}

{% renderTemplate "md" %}
# I am a title

* I am a list
* I am a list
{% endrenderTemplate %}

{% endraw %}

{% codetitle "JavaScript", "Syntax" %}

{% raw %}

module.exports = async function() {
  return await this.renderTemplate(`# I am a title

* I am a list
* I am a list`, "md");
};

{% endraw %}

The renderTemplate shortcode requires an async-friendly template language and is not available in Handlebars.

The content inside of the shortcode will be rendered using Markdown ("md"). Front matter is not yet supported.

The first argument to renderTemplate can be any valid templateEngineOverride value. You can even use "liquid,md" to preprocess markdown with liquid. You can use custom template types here too, including the Vue plugin!

{% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "rendertmplvue"} %}

{% raw %}

{% renderTemplate "vue" %}
<div>
  THIS IS VUE <p v-html="hi"></p>
</div>
{% endrenderTemplate %}

{% endraw %}

{% raw %}

{% renderTemplate "vue" %}
<div>
  THIS IS VUE <p v-html="hi"></p>
</div>
{% endrenderTemplate %}

{% endraw %}

{% codetitle "JavaScript", "Syntax" %}

{% raw %}

module.exports = async function() {
  return await this.renderTemplate(`<div>
  THIS IS VUE <p v-html="hi"></p>
</div>`, "vue");
};

{% endraw %}

The renderTemplate shortcode requires an async-friendly template language and is not available in Handlebars.

{% callout "info", "md" %}The one exception here is that {% raw %}{% renderTemplate "11ty.js" %}{% endraw %} JavaScript string templates are not yet supported—use renderFile below instead.{% endcallout %}

To add Vue support, don’t forget to install @11ty/eleventy-plugin-vue (v0.6.0 or newer) and add the Vue plugin in your config file. There is an example on the Eleventy Vue Plugin documentation showing how to call the render plugin inside of Vue components.

Pass in data

Both the eleventy and page variables are available inside of these templates by default. If you want to pass in additional data, you can do so like this:

{% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "rendertmpldata"} %}

{% codetitle "Liquid", "Syntax" %}

{% raw %}

---
myData:
  myKey: myValue
---
{% renderTemplate "liquid", myData %}
{{ myKey }}
{% endrenderTemplate %}

{% endraw %}

{% codetitle "Nunjucks", "Syntax" %}

{% raw %}

---
myData:
  myKey: myValue
---
{% renderTemplate "liquid", myData %}
{{ myKey }}
{% endrenderTemplate %}

{% endraw %}

{% codetitle "JavaScript", "Syntax" %}

{% raw %}

module.exports.data = {
  myData: {
    myKey: "myValue"
  }
};
module.exports.render = async function(data) {
  return await this.renderTemplate(`{{ myKey }}`, "liquid", data.myData);
};

{% endraw %}

The renderTemplate shortcode requires an async-friendly template language and is not available in Handlebars.

Outputs myValue.

renderFile

Use the renderFile shortcode to render an include file.

{% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "renderfile"} %}

{% codetitle "Liquid", "Syntax" %}

{% raw %}

{% renderFile "./_includes/blogpost.md" %}

{% endraw %}

{% codetitle "Nunjucks", "Syntax" %}

{% raw %}

{% renderFile "./_includes/blogpost.md" %}

{% endraw %}

{% codetitle "JavaScript", "Syntax" %}

{% raw %}

module.exports = async function() {
  return await this.renderFile("./includes/blogpost.md");
};

{% endraw %}

The renderFile shortcode requires an async-friendly template language and is not available in Handlebars.

The first argument to renderFile is a project root relative path to any template file. Front matter inside of the target files is not yet supported. The template syntax used is inferred by the file extension.

Note that you can use files supported by any custom file extensions you’ve added too, including a Vue Single File Component from the Eleventy Vue plugin!

{% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "renderfilevue"} %}

{% codetitle "Liquid", "Syntax" %}

{% raw %}

{% renderFile "./_includes/header.vue" %}

{% endraw %}

{% codetitle "Nunjucks", "Syntax" %}

{% raw %}

{% renderFile "./_includes/header.vue" %}

{% endraw %}

{% codetitle "JavaScript", "Syntax" %}

{% raw %}

module.exports = async function() {
  return await this.renderFile("./includes/header.vue");
};

{% endraw %}

The renderFile shortcode requires an async-friendly template language and is not available in Handlebars.

To add Vue support, don’t forget to install @11ty/eleventy-plugin-vue (v0.6.0 or newer) and add the Vue plugin in your config file.

Pass in data

Both the eleventy and page variables are available inside of these templates by default. If you want to pass in additional data, you can do so like this:

{% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "renderfiledata"} %}

{% codetitle "Liquid", "Syntax" %}

{% raw %}

---
myData:
  myKey: myValue
---
{% renderFile "./_includes/blogpost.md", myData %}

{% endraw %}

{% codetitle "Nunjucks", "Syntax" %}

{% raw %}

---
myData:
  myKey: myValue
---
{% renderFile "./_includes/blogpost.md", myData %}

{% endraw %}

{% codetitle "JavaScript", "Syntax" %}

{% raw %}

module.exports.data = {
  myData: {
    myKey: "myValue"
  }
};
module.exports.render = async function(data) {
  return await this.renderFile("./includes/blogpost.md", data.myData);
};

{% endraw %}

The renderFile shortcode requires an async-friendly template language and is not available in Handlebars.

Override the target file syntax

The syntax is normally inferred using the file extension, but it can be overridden using a third argument. It can be any valid templateEngineOverride value. You can even use "liquid,md" to preprocess markdown with liquid.

{% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "renderfileoverride"} %}

{% codetitle "Liquid", "Syntax" %}

{% raw %}

---
myData:
  key: value
---
{% renderFile "./_includes/blogpost.md", myData, "njk" %}

{% endraw %}

{% codetitle "Nunjucks", "Syntax" %}

{% raw %}

---
myData:
  key: value
---
{% renderFile "./_includes/blogpost.md", myData, "njk" %}

{% endraw %}

{% codetitle "JavaScript", "Syntax" %}

{% raw %}

module.exports.data = {
  myData: {
    myKey: "myValue"
  }
};
module.exports.render = async function(data) {
  return await this.renderFile("./includes/blogpost.md", data.myData, "njk");
};

{% endraw %}

The renderFile shortcode requires an async-friendly template language and is not available in Handlebars.

Will render blogpost.md using Nunjucks instead of Markdown!